/*******************************************************************************
 * Copyright 2011-2012 Dik Grapendaal
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 ******************************************************************************/
package sh.grapendaal.tsuushin.service;

import sh.grapendaal.tsuushin.core.BotFilter;
import sh.grapendaal.tsuushin.core.IrcBot;
import sh.grapendaal.tsuushin.core.Network;

/**
 * The Bot Service contains methods which deal with the IRC bots. This includes
 * retrieving a bot which meets certain specifications, creating new bots and
 * (re)connecting bots.
 */
public interface BotService extends Service {
	/**
	 * Creates a new bot with the specified nickname, which will connect to the
	 * specified network.
	 * 
	 * @param nickname
	 *            The nickname for the bot.
	 * @param network
	 *            The network to connect to.
	 * @return A new Bot instance.
	 */
	IrcBot createBot(String nickname, Network network);

	/**
	 * Connects any unconnected bots to their specified network.
	 */
	void connectBots();

	/**
	 * Schedules a connect for the given bot.
	 * 
	 * @param bot
	 *            The bot to schedule a reconnect for.
	 */
	void scheduleConnect(IrcBot bot);

	/**
	 * Returns a BotFilter for all the currently running bots. The BotFilter can
	 * be used to lookup one or more specific bots, filtered by one or more
	 * rules.
	 * 
	 * @return A BotFilter object with all currently running bots.
	 */
	BotFilter filter();
}
